Documentation: workspace.open( ) with no URI #6005
Conversation
I just learned that [calling open on workspace](https://discuss.atom.io/t/how-can-we-help-you-write-packages/4268/67) without specifying an uri is the way to go for getting a new tab with a new document. I can't find anything about this in either the docs or the [api documentation.](https://atom.io/docs/api/v0.187.0/Workspace#instance-open) Should `uri` be marked optional, like the `options` params? And should it be added a line stating that no uri opens a blank editor? (and there's an extra `a` in the title..)
|
This makes sense to me. What do you think, @nathansobo -- is it 🆒 to document this behavior? |
|
Yeah, documenting that would be great. |
| # | ||
| # * `uri` A {String} containing a URI. | ||
| # Essential: Open a given URI in Atom asynchronously. | ||
| # If no URI is given, or URI does not resolve to an existing file, |
There was a problem hiding this comment.
Perhaps instead of saying:
or URI does not resolve to an existing file,
we could say something like
or URI is not already open in an existing pane item
because URIs are used to reference and open more than files. For example, atom.workspace.open("atom://config") can be used to open the Settings View. What do you think, @vegar?
There was a problem hiding this comment.
First: I have been looking at atom for three spare nights now. I have very little knowledge of how it works.
What I found, was that if we have atom.workspace.open("file_not_on_disk.txt"), we get a new editor/document where the filename is initalized to the URI, so if you hit save you wan't be prompted for a filename - it will just save the file in the root of the current project.
If you do not have a project open, you will still get a new document, but the document will not get the filename specified. It will get 'untitled'.
So the proposed text .., or URI does not resolve to an existingn file, ... was supposed to capture some of this behavior. Not a very clear formulation I guess.. 😳 ..but that was it's intent.
I think maybe your proposed change will document yet another behavior that I was unaware of. Maybe it should be added as a separate bullet point? (The documentation guidelines may have an opinion on how behavior should be listed?)
There was a problem hiding this comment.
What I found, was that if we have atom.workspace.open("file_not_on_disk.txt"), we get a new editor/document where the filename is initalized to the URI, so if you hit save you wan't be prompted for a filename - it will just save the file in the root of the current project.
If you do not have a project open, you will still get a new document, but the document will not get the filename specified. It will get 'untitled'.
@vegar I'd skip documenting this stuff around untitled filenames for now, especially not here since you're referring to something that will happen on save, and the user might not even save the file. I think my proposed change reflects the behavior related to opening, which is the method we are documenting here. Sound good?
There was a problem hiding this comment.
Also cc @nathansobo in case he has different opinions on this.
There was a problem hiding this comment.
@vegar Just to make sure I understand -- does that 👍 mean that you want to update the PR to clarify the text based on my above suggestion? https://github.com/atom/atom/pull/6005/files#r26837887 I'm still in favor of making that update.
There was a problem hiding this comment.
It was me agreeing to not documenting all the save-related behavior here.
About your initial suggesting: replacing
or URI does not resolve to an existing file,
with
or URI is not already open in an existing pane item
I'm not sure what's best.
Your suggestion states that if the uri is already open, it wan't open again, but is that true? Or is that dependent on how the open handler are implemented? (Cause in a small test project I have, I get multiple tabs with the same uri... ..not that I wanted to, but I can't find out how to prevent it...)
My suggestion states that if the uri is a file uri but the file doesn't exist, you will get a new text editor.
So... What about
Essential: Opens a given URI in Atom asynchronously, if it's not already open.
If no URI is given, or URI is a filepath and the file does not exist, a new empty text editor is created.
or
..., or URI is to a file that does not exist, ...
There was a problem hiding this comment.
I don't have strong opinions here, as long as we're accurate. I do like ensuring our language makes clear that URIs don't always correspond to paths on disk.
Documentation: workspace.open( ) with no URI
|
This is merged now, I just made a minor clarification in b8fb2f4. Thanks again for this. |
I just learned that calling open on workspace without specifying an uri is the way to go for getting a new tab with a new document.
I can't find anything about this in either the docs or the api documentation.
Should
uribe marked optional, like theoptionsparams? And should it be added a line stating that no uri opens a blank editor?(and there's an extra
ain the title..)